DEFINITION MODULE fsWalk; (* Leo 13-Oct-89. (c) KRONOS *)

(* Прогуливается по файловому дереву. *)

IMPORT  BIO;

TYPE TREE;

VAL null: TREE;
     pos: INTEGER; (* position where error 'bad_name' occured *)
    done: BOOLEAN;
   error: INTEGER;

(* all procedures if it is'nt specialy declared      *)
(* set 'done=TRUE' if operation done OK, else        *)
(* they set 'done=FALSE' and 'error=cause of error' *)

PROCEDURE walk(VAR fs: TREE; patt: ARRAY OF CHAR; only_files: BOOLEAN);
(* start of tree search *)

PROCEDURE match(fs: TREE; fullpathname: ARRAY OF CHAR; pos: INTEGER): BOOLEAN;

PROCEDURE matched_len(fs: TREE; n: CHAR): INTEGER;
PROCEDURE matched_pos(fs: TREE; n: CHAR): INTEGER;
(* returns length and position start of substring *)
(* matched to $n at last call of 'match' proc     *)
(* n IN ["1".."9","@","."                         *)

PROCEDURE next_dir(fs: TREE): BOOLEAN;
(* returns FALSE when tree iteration finished *)

PROCEDURE dir(fs: TREE): BIO.FILE; (* may return BIO.NULL *)
(* returns directory in tree after 'next_dir' *)

PROCEDURE dpath(fs: TREE; VAR path: ARRAY OF CHAR); (* not side effect to *)
PROCEDURE dname(fs: TREE; VAR name: ARRAY OF CHAR); (* "done" and "error" *)

PROCEDURE next_entry(fs: TREE;
               VAR name: ARRAY OF CHAR; VAR mode: BITSET): BOOLEAN;
(* returns FALSE when next entry not found in the directory *)

PROCEDURE substitute(fs: TREE; model: ARRAY OF CHAR;
                            VAR dest: ARRAY OF CHAR);

PROCEDURE restart_dir(fs: TREE);
(* restart search at directory *)

PROCEDURE fpath(fs: TREE; VAR path: ARRAY OF CHAR); (* not side effect to *)
PROCEDURE fname(fs: TREE; VAR name: ARRAY OF CHAR); (*                    *)
PROCEDURE fmode(fs: TREE; VAR mode: BITSET);        (* "done" and "error" *)

PROCEDURE restart_walk(fs: TREE);
(* global restart of tree *)

PROCEDURE dispose(VAR fs: TREE);
(* terminate tree search and dispose all memory occupied by the TREE *)

(***************************************************************

PROCEDURE walk(VAR fs: TREE; pattern: ARRAY OF CHAR; only_files: BOOLEAN);
--------------

 pattern      = root_prefix path_pattern node_pattern .
 root_prefix  = [ "/" ] .
 path_pattern = { RE "/" } tree_postfix .
 tree_postfix = [ "/" ] .
 RE           = 'any regular expresion without "/" '

 if syntax error in pattern occured then
 'pos' pointed at error position

 file_pattern determine pattern for
 all files at tree nodes iterated by 'next_entry'.
 if 'fileonly'=TRUE then names of subdirectories
 not generatedv by 'next_entry' call.

 ".." NEVER generated by 'next_entry' call.

 ".." may be used as a 'pathpattern' BUT without $<digit> and

 parenthis:
    /util/*/(..)$1/*/*.@  are legal but has empty result
    /util/*/../*/*.@      are legal and has good  result

 Before (and only before!) file_pattern "//" determines
 sub-tree iteration.

 Examples:

   .//*.?          all files *.? at current and subdirectorities
   //my_best.file  all "my_best.file" files in file tree

   /util/*/(?*.[md@])$1

 ILLEGAL:

   /usr//tmp/../..//leo/*
                   theoretical possible but very difficult in
                   implementation, so, not realized yet.
                   (may be later...)

***************************************************************)

END fsWalk.
